#ifndef RING_BUFFER_H
#define RING_BUFFER_H

#include <stdint.h>
#include <stdbool.h>
#include <stdlib.h>

// 环形缓冲结构体（不透明类型，用户无需关心内部实现）
typedef struct RingBuffer RingBuffer;

/**
 * @brief 创建环形缓冲实例（动态内存分配）
 * @param size 缓冲大小（字节数，建议为2的幂数）
 * @return 成功返回环形缓冲指针，失败返回NULL
 * @note 需要调用ringbuf_destroy释放资源
 */
RingBuffer* ringbuf_create(uint16_t size);

/**
 * @brief 初始化静态分配的环形缓冲
 * @param rb 预分配的环形缓冲结构体指针
 * @param buffer 数据存储缓冲区（用户提供）
 * @param size 缓冲大小（字节数，建议为2的幂数）
 * @return 成功返回true，失败返回false（参数无效时）
 * @note 适用于资源受限场景，无需动态内存分配
 */
bool ringbuf_init_static(RingBuffer* rb, uint8_t* buffer, uint16_t size);

/**
 * @brief 销毁环形缓冲实例（释放动态分配的资源）
 * @param rb 环形缓冲指针
 */
void ringbuf_destroy(RingBuffer* rb);

/**
 * @brief 向环形缓冲写入一个字节
 * @param rb 环形缓冲实例
 * @param data 待写入的数据
 * @return 写入成功返回true，缓冲满返回false
 */
bool ringbuf_push(RingBuffer* rb, uint8_t data);

/**
 * @brief 从环形缓冲读取一个字节
 * @param rb 环形缓冲实例
 * @param data 读取数据的存储地址
 * @return 读取成功返回true，缓冲空返回false
 */
bool ringbuf_pop(RingBuffer* rb, uint8_t* data);

/**
 * @brief 检查环形缓冲是否为空
 * @param rb 环形缓冲实例
 * @return 为空返回true，否则返回false
 */
bool ringbuf_is_empty(RingBuffer* rb);

/**
 * @brief 检查环形缓冲是否已满
 * @param rb 环形缓冲实例
 * @return 已满返回true，否则返回false
 */
bool ringbuf_is_full(RingBuffer* rb);

/**
 * @brief 获取环形缓冲中的有效数据长度
 * @param rb 环形缓冲实例
 * @return 有效数据字节数
 */
uint16_t ringbuf_get_length(RingBuffer* rb);

/**
 * @brief 获取环形缓冲的总容量
 * @param rb 环形缓冲实例
 * @return 缓冲总大小（字节数）
 */
uint16_t ringbuf_get_capacity(RingBuffer* rb);

/**
 * @brief 清空环形缓冲
 * @param rb 环形缓冲实例
 */
void ringbuf_clear(RingBuffer* rb);





// 声明全局环形缓冲区指针（关键：用extern，不分配内存）
extern RingBuffer* uart0_ringbuf;  // 供全局引用的UART0缓冲区
extern RingBuffer* uart1_ringbuf;  // （可选）UART1缓冲区
void ringbuf_global_init(void);


#endif  // RING_BUFFER_H